/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.solr.util.hll;

/**
 * A serialization schema for HLLs. Reads and writes HLL metadata to and from <code>byte[]</code>
 * representations.
 */
public interface ISchemaVersion {
  /**
   * The number of metadata bytes required for a serialized HLL of the specified type.
   *
   * @param type the type of the serialized HLL
   * @return the number of padding bytes needed in order to fully accommodate the needed metadata.
   */
  int paddingBytes(HLLType type);

  /**
   * Writes metadata bytes to serialized HLL.
   *
   * @param bytes the padded data bytes of the HLL
   * @param metadata the metadata to write to the padding bytes
   */
  void writeMetadata(byte[] bytes, IHLLMetadata metadata);

  /**
   * Reads the metadata bytes of the serialized HLL.
   *
   * @param bytes the serialized HLL
   * @return the HLL metadata
   */
  IHLLMetadata readMetadata(byte[] bytes);

  /**
   * Builds an HLL serializer that matches this schema version.
   *
   * @param type the HLL type that will be serialized. This cannot be <code>null</code>.
   * @param wordLength the length of the 'words' that comprise the data of the HLL. Words must be at
   *     least 5 bits and at most 64 bits long.
   * @param wordCount the number of 'words' in the HLL's data.
   * @return a byte array serializer used to serialize a HLL according to this schema version's
   *     specification.
   * @see #paddingBytes(HLLType)
   * @see IWordSerializer
   */
  IWordSerializer getSerializer(HLLType type, int wordLength, int wordCount);

  /**
   * Builds an HLL deserializer that matches this schema version.
   *
   * @param type the HLL type that will be deserialized. This cannot be <code>null</code>.
   * @param wordLength the length of the 'words' that comprise the data of the serialized HLL. Words
   *     must be at least 5 bits and at most 64 bits long.
   * @param bytes the serialized HLL to deserialize. This cannot be <code>null</code>.
   * @return a byte array deserializer used to deserialize a HLL serialized according to this schema
   *     version's specification.
   */
  IWordDeserializer getDeserializer(HLLType type, int wordLength, byte[] bytes);

  /**
   * @return the schema version number.
   */
  int schemaVersionNumber();
}
